home *** CD-ROM | disk | FTP | other *** search
/ Megahits 5 / Megahits 5 (1994)(GTI - Rhein-Main-Soft)(DE)(Disc 2 of 2)[!].iso / archive / show / supervlib83dev.lha / superview-lib_DEV / Programmers / Docs / SVSupport_Ref_ENG.doc < prev    next >
Text File  |  1994-09-21  |  25KB  |  1,113 lines
  1.  
  2.    $VER: SVSupport_Reference.doc V4.2 (8.7.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.        Andreas R. Kleinert,
  9.        Grube Hohe Grethe 23,
  10.        D-57074 Siegen,
  11.        Germany.                        email : Fido 2:2457/345.10
  12.                                                (checked weekly)
  13.  
  14.  
  15.    Here is a listing of all currently available functions of the
  16.    superviewsupport.library in an Autodoc-like style of description :
  17.  
  18.         SVSUP_GetMemList           ; since Version 1
  19.         SVSUP_FreeMemList
  20.         SVSUP_AddMemEntry
  21.         SVSUP_AllocMemEntry
  22.         SVSUP_CheckInterleaved
  23.         SVSUP_GetXAspect
  24.         SVSUP_GetYAspect
  25.         SVSUP_GetBitMapDepth
  26.         SVSUP_GetBitMapHeight
  27.         SVSUP_GetBodySize
  28.         SVSUP_GetStdScreenSize
  29.         SVSUP_GetBestModeID
  30.         SVSUP_CopyScreenToBuffer8   *** OBSOLETE : Use ScreenToOnePlane8
  31.         SVSUP_LoadControlPad       ; since Version 2
  32.         SVSUP_SaveControlPad
  33.         SVSUP_FreeControlPad
  34.         SVSUP_FindControlPad
  35.         SVSUP_BitPlaneToOnePlane8  ; since Version 3
  36.         SVSUP_OnePlaneToBitPlane8
  37.         SVSUP_ScreenToOnePlane8
  38.         SVSUP_ScreenToBitPlane8
  39.         SVSUP_DisplayGfxBuffer     ; since Version 4
  40.         SVSUP_UnDisplayGfxBuffer
  41.         SVSUP_FreeGfxBuffer
  42.  
  43. -----------------------------------------------------------------------------
  44.    Functions available since Version 1 :
  45. -----------------------------------------------------------------------------
  46.  
  47.    NAME
  48.         SVSUP_GetMemList
  49.  
  50.    SYNOPSIS
  51.  
  52.         APTR SVSUP_GetMemList(void)
  53.         D0   -$1e
  54.  
  55.    FUNCTION
  56.  
  57.         Allocates a handle for accessing a memory allocation list.
  58.  
  59.    INPUT(S)
  60.  
  61.         -
  62.  
  63.    RESULT
  64.  
  65.         A pointer to a new allocated Handle or NULL, if allocation failed.
  66.  
  67.    WARNING
  68.  
  69.         Test, if the result was NULL, or not !
  70.  
  71.    BUGS
  72.  
  73.         -
  74.  
  75.    SINCE
  76.  
  77.         ... version 1 of the superviewsupport.library.
  78.  
  79.    SEE ALSO
  80.  
  81.         SVSUP_FreeMemList
  82.  
  83. -----------------------------------------------------------------------------
  84.  
  85.    NAME
  86.         SVSUP_FreeMemList
  87.  
  88.    SYNOPSIS
  89.  
  90.         VOID SVSUP_FreeMemList(APTR handle)
  91.         D0   -$24              A1
  92.  
  93.    FUNCTION
  94.  
  95.        Frees all memory from the given memory allocation list
  96.        and also delocates the list itself !
  97.  
  98.    INPUT(S)
  99.  
  100.        handle - a valid handle
  101.  
  102.    RESULT
  103.  
  104.         -
  105.  
  106.    SINCE
  107.  
  108.         ... version 1 of the superviewsupport.library.
  109.  
  110.    SEE ALSO
  111.  
  112.         SVSUP_GetMemList
  113.  
  114. -----------------------------------------------------------------------------
  115.  
  116.    NAME
  117.         SVSUP_AddMemEntry
  118.  
  119.    SYNOPSIS
  120.  
  121.         ULONG SVSUP_AddMemEntry(APTR handle, APTR pointer)
  122.         D0    -$2a              A1           A2
  123.  
  124.    FUNCTION
  125.  
  126.         Adds an "AllocVec"ed memory pointer to the memory list,
  127.         to be remembered for delocation later.
  128.  
  129.    INPUT(S)
  130.  
  131.         handle  - a valid handle
  132.         pointer - a pointer to a chunk of memory, which has been
  133.                   allocated with Exec's AllocVec() function
  134.  
  135.    RESULT
  136.  
  137.         Boolean value : The memory will be freed immediately, if
  138.         remembering failed.
  139.  
  140.    BUGS
  141.  
  142.         -
  143.  
  144.    SINCE
  145.  
  146.         ... version 1 of the superviewsupport.library.
  147.  
  148.    SEE ALSO
  149.  
  150.         SVSUP_FreeMemList
  151.  
  152. -----------------------------------------------------------------------------
  153.  
  154.    NAME
  155.         SVSUP_AllocMemEntry
  156.  
  157.    SYNOPSIS
  158.  
  159.         APTR SVSUP_AllocMemEntry(APTR handle, size, type)
  160.         D0   -$30                A1           D0    D1
  161.  
  162.    FUNCTION
  163.  
  164.         Allocates memory just like AllocVec(), but remembers this
  165.         in the given memory allocation list.
  166.  
  167.    INPUT(S)
  168.  
  169.         handle - a valid handle
  170.         size   - needed size for the memory chunk
  171.         type   - "MEMF_"-specification of the memory type
  172.  
  173.    RESULT
  174.  
  175.         pointer to memory or NULL.
  176.  
  177.    BUGS
  178.  
  179.         -
  180.  
  181.    SINCE
  182.  
  183.         ... version 1 of the superviewsupport.library.
  184.  
  185.    SEE ALSO
  186.  
  187.         SVSUP_GetMemList, SVSUP_FreeMemList
  188.  
  189. -----------------------------------------------------------------------------
  190.  
  191.    NAME
  192.         SVSUP_CheckInterleaved
  193.  
  194.    SYNOPSIS
  195.  
  196.         ULONG SVSUP_CheckInterleaved(struct Screen *sc)
  197.         D0    -$36                   A1
  198.  
  199.    FUNCTION
  200.  
  201.         Is the BitMap of the given Screen of type "interleaved"
  202.         (possible since OS V39 with AGA) ?
  203.  
  204.    INPUT(S)
  205.  
  206.         sc - a valid Screen Pointer
  207.  
  208.    RESULT
  209.  
  210.         Boolean value.
  211.  
  212.    BUGS
  213.  
  214.         -
  215.  
  216.    SINCE
  217.  
  218.         ... version 1 of the superviewsupport.library.
  219.  
  220.    SEE ALSO
  221.  
  222.         -
  223.  
  224. -----------------------------------------------------------------------------
  225.  
  226.    NAME
  227.         SVSUP_GetXAspect
  228.  
  229.    SYNOPSIS
  230.  
  231.         UBYTE SVSUP_GetXAspect(struct Screen *sc)
  232.         D0    -$3c             A1
  233.  
  234.    FUNCTION
  235.  
  236.         Calculates an ILBM compatible XAspect-value for any ScreenMode.
  237.  
  238.    INPUT(S)
  239.  
  240.         sc - a valid Screen Pointer
  241.  
  242.    RESULT
  243.  
  244.         XAspect value for the given Screen.
  245.  
  246.    BUGS
  247.  
  248.         -
  249.  
  250.    SINCE
  251.  
  252.         ... version 1 of the superviewsupport.library.
  253.  
  254.    SEE ALSO
  255.  
  256.         SVSUP_GetXAspect
  257.  
  258. -----------------------------------------------------------------------------
  259.  
  260.    NAME
  261.         SVSUP_GetYAspect
  262.  
  263.    SYNOPSIS
  264.  
  265.         UBYTE SVSUP_GetYAspect(struct Screen *sc)
  266.         D0    -$42             A1
  267.  
  268.    FUNCTION
  269.  
  270.         Calculates an ILBM compatible YAspect-value for any ScreenMode.
  271.  
  272.    INPUT(S)
  273.  
  274.         sc - a valid Screen Pointer
  275.  
  276.    RESULT
  277.  
  278.         YAspect value for the given Screen.
  279.  
  280.    BUGS
  281.  
  282.         -
  283.  
  284.    SINCE
  285.  
  286.         ... version 1 of the superviewsupport.library.
  287.  
  288.    SEE ALSO
  289.  
  290.         SVSUP_GetXAspect
  291.  
  292. -----------------------------------------------------------------------------
  293.  
  294.    NAME
  295.         SVSUP_GetBitMapDepth
  296.  
  297.    SYNOPSIS
  298.  
  299.         ULONG SVSUP_GetBitMapDepth(struct Screen *sc)
  300.         D0    -$48                 A1
  301.  
  302.    FUNCTION
  303.  
  304.         Finds out the depth of the BitMap of a given Screen.
  305.         This is safer than accessing the various structures under V39+.
  306.  
  307.    INPUT(S)
  308.  
  309.         sc - a valid Screen Pointer
  310.  
  311.    RESULT
  312.  
  313.         depth of the Screen's BitMap.
  314.  
  315.    BUGS
  316.  
  317.         -
  318.  
  319.    SINCE
  320.  
  321.         ... version 1 of the superviewsupport.library.
  322.  
  323.    SEE ALSO
  324.  
  325.         SVSUP_GetBitMapHeight
  326.  
  327. -----------------------------------------------------------------------------
  328.  
  329.    NAME
  330.         SVSUP_GetBitMapHeight
  331.  
  332.    SYNOPSIS
  333.  
  334.         ULONG SVSUP_GetBitMapHeight(struct Screen *sc)
  335.         D0    -$4e                 A1
  336.  
  337.    FUNCTION
  338.  
  339.         Finds out the height of the BitMap of a given Screen.
  340.         This is safer than accessing the various structures under V39+.
  341.  
  342.    INPUT(S)
  343.  
  344.         sc - a valid Screen Pointer
  345.  
  346.    RESULT
  347.  
  348.         height of the Screen's BitMap.
  349.  
  350.    BUGS
  351.  
  352.         -
  353.  
  354.    SINCE
  355.  
  356.         ... version 1 of the superviewsupport.library.
  357.  
  358.    SEE ALSO
  359.  
  360.         SVSUP_GetBitMapDepth
  361.  
  362. -----------------------------------------------------------------------------
  363.  
  364.    NAME
  365.         SVSUP_GetBodySize
  366.  
  367.    SYNOPSIS
  368.  
  369.         ULONG SVSUP_GetBodySize(struct Screen *sc)
  370.         D0    -$54              A1
  371.  
  372.    FUNCTION
  373.  
  374.         This function calculates the size of a buffer to hold the
  375.         given Screen's BitMap.
  376.         As the name reflects, this buffer confirms to the needs
  377.         of a "BODY" (or ABIT) chunk for ILBM (or ACBM) Files.
  378.         No alignment things are done.
  379.  
  380.    INPUT(S)
  381.  
  382.         sc - a valid Screen Pointer
  383.  
  384.    RESULT
  385.  
  386.         NULL or an adequate SVERR-Errorcode.
  387.  
  388.    BUGS
  389.  
  390.         -
  391.  
  392.    SINCE
  393.  
  394.         ... version 1 of the superviewsupport.library.
  395.  
  396.    SEE ALSO
  397.  
  398.         -
  399.  
  400. -----------------------------------------------------------------------------
  401.  
  402.    NAME
  403.         SVSUP_GetStdScreenSize
  404.  
  405.    SYNOPSIS
  406.  
  407.         ULONG SVSUP_GetStdScreenSize(ULONG mode_id, ULONG *width,
  408.         D0    -$5a                   D0             A1
  409.  
  410.                                      ULONG *height)
  411.                                      A2
  412.  
  413.  
  414.    FUNCTION
  415.  
  416.         Gets the standard dimensions for a given ScreenMode.
  417.         For e.g. "PAL:HighRes", this would be 640 and 256.
  418.         The values are written into the supplied ULONGs.
  419.  
  420.         This function may FAIL !
  421.  
  422.    INPUT(S)
  423.  
  424.         sc - a valid Screen Pointer
  425.  
  426.    RESULT
  427.  
  428.         Boolean value.
  429.  
  430.    BUGS
  431.  
  432.         -
  433.  
  434.    SINCE
  435.  
  436.         ... version 1 of the superviewsupport.library.
  437.  
  438.    SEE ALSO
  439.  
  440.         SVSUP_SuperView
  441.  
  442. -----------------------------------------------------------------------------
  443.  
  444.    NAME
  445.         SVSUP_GetBestModeID
  446.  
  447.    SYNOPSIS
  448.  
  449.         ULONG SVSUP_GetBestModeID(ULONG width, ULONG height, ULONG depth)
  450.         D0    -$60                D0           D1            D2
  451.  
  452.    FUNCTION
  453.  
  454.         Returns the best ScreenMode ID for a hypothetical Screen with the
  455.         given dimensions.
  456.         Under V37 ECS is assumed, under V39 the appropriate Gfx-Library's
  457.         function is used for that.
  458.  
  459.    INPUT(S)
  460.  
  461.         width, height, depth - Screen dimension values
  462.  
  463.    RESULT
  464.  
  465.         a ModeID value.
  466.  
  467.    BUGS
  468.  
  469.         -
  470.  
  471.    SINCE
  472.  
  473.         ... version 1 of the superviewsupport.library.
  474.  
  475.    SEE ALSO
  476.  
  477.         -
  478.  
  479. -----------------------------------------------------------------------------
  480.  
  481.    NAME
  482.         SVSUP_CopyScreenToBuffer8   *** OBSOLETE : Use ScreenToOnePlane8
  483.  
  484.    SYNOPSIS
  485.  
  486.         ULONG SVSUP_CopyScreenToBuffer8(struct Screen *sc, UBYTE *buffer,
  487.         D0    -$66                      A1           A2
  488.  
  489.                                         ULONG width, ULONG height,
  490.                                         D0           D1
  491.  
  492.                                         ULONG depth)
  493.                                         D2
  494.  
  495.    FUNCTION
  496.  
  497.         *** You should use SVSUP_ScreenToOnePlane8() instead, which
  498.             is more easy to handle and uses this function, anyway ...
  499.  
  500.         This function copies the content of a common Intuition Screen
  501.         into a buffer in the "ChunkyPixel" (8 Bit) format.
  502.         The buffer itself (with size = width * height) has to be supplied.
  503.         The width, height and depth values (depth must be smaller than 8)
  504.         have to be supplied also. These are not read from the Screen.
  505.  
  506.         This function may FAIL.
  507.  
  508.    INPUT(S)
  509.  
  510.         sc     - a valid ScreenPointer
  511.         buffer - a pointer to a buffer with size = width * height
  512.         width  - Screen's Width
  513.         height - Screen's Height
  514.         depth  - Screen's Depth
  515.  
  516.    RESULT
  517.  
  518.         Boolean value.
  519.  
  520.    BUGS
  521.  
  522.         -
  523.  
  524.    SINCE
  525.  
  526.         ... version 1 of the superviewsupport.library.
  527.  
  528.    SEE ALSO
  529.  
  530.         SVSUP_SuperWrite
  531.  
  532. -----------------------------------------------------------------------------
  533.    Functions available since Version 2 :
  534. -----------------------------------------------------------------------------
  535.  
  536.    NAME
  537.         SVSUP_LoadControlPad
  538.  
  539.    SYNOPSIS
  540.  
  541.         ULONG SVSUP_LoadControlPad(UBYTE *filename, struct SV_ControlPad **pad)
  542.         D0    -$6c                 A1               A2
  543.  
  544.    FUNCTION
  545.  
  546.         Opens and reads a standard Configuration File for superview.library's
  547.         SVObjects, SVDrivers, etc.
  548.         It consists of Tooltype-like entries in the form :
  549.         <Name>=<Content> or <Keyword>, where each entry is built of one
  550.         line of the file.
  551.         All lines beginning with "/" or ";" or just blank lines are handled
  552.         as comments and are ignored.
  553.  
  554.         All ControlPads are chained in a single-linked List.
  555.         Remember to save the head-pointer to the List somewhere,
  556.         because it's needed for free'ing the List.
  557.  
  558.         Only READ-ACCESSES should be done to the list entries, but if you
  559.         want to add more entries to the list, note that all entries have
  560.         to be allocated with AllocVec() and delocated with FreeVec().
  561.  
  562.    INPUT(S)
  563.  
  564.         filename - a FileName for AmigaDOS
  565.         pad      - a pointer to a ControlPad-Structure pointer
  566.  
  567.    RESULT
  568.  
  569.         Boolean value.
  570.  
  571.         If the function returned FALSE, pad will also be NULL.
  572.  
  573.    BUGS
  574.  
  575.         SVSUP_FindControlPad, SVSUP_SaveControlPad, SVSUP_FreeControlPad
  576.  
  577.    SINCE
  578.  
  579.         ... version 2 of the superviewsupport.library.
  580.  
  581.    SEE ALSO
  582.  
  583.         -
  584.  
  585. -----------------------------------------------------------------------------
  586.  
  587.    NAME
  588.         SVSUP_SaveControlPad
  589.  
  590.    SYNOPSIS
  591.  
  592.         ULONG SVSUP_SaveControlPad(UBYTE *filename, struct SV_ControlPad *pad)
  593.         D0    -$72                 A1               A2
  594.  
  595.    FUNCTION
  596.  
  597.         Writes a standard Configuration File for superview.library's
  598.         SVObjects, SVDrivers, etc.
  599.  
  600.         You have to supply your own ControlPad-List (or one supplied from
  601.         SVSUP_LoadControlPad).
  602.  
  603.    INPUT(S)
  604.  
  605.         filename - a FileName for AmigaDOS
  606.         pad      - a pointer to a ControlPad-Structure (List-Head)
  607.  
  608.    RESULT
  609.  
  610.         Boolean value.
  611.  
  612.    BUGS
  613.  
  614.         -
  615.  
  616.    SINCE
  617.  
  618.         ... version 2 of the superviewsupport.library.
  619.  
  620.    SEE ALSO
  621.  
  622.         SVSUP_FindControlPad, SVSUP_LoadControlPad, SVSUP_FreeControlPad
  623.  
  624. -----------------------------------------------------------------------------
  625.  
  626.    NAME
  627.         SVSUP_FreeControlPad
  628.  
  629.    SYNOPSIS
  630.  
  631.         ULONG SVSUP_FreeControlPad(struct SV_ControlPad *pad)
  632.         D0    -$78                 A1
  633.  
  634.    FUNCTION
  635.  
  636.         Frees a single-chained list of ControlPads, which has been
  637.         allocated and initialized via SVSUP_LoadControlPad() before.
  638.  
  639.         If you want to free your own, self-created ControlPad lists,
  640.         note that all entries have to be allocated with AllocVec() and
  641.         delocated with FreeVec().
  642.  
  643.    INPUT(S)
  644.  
  645.         pad      - a pointer to a ControlPad-Structure (List-Head)
  646.  
  647.    RESULT
  648.  
  649.         Boolean value.
  650.  
  651.         (returns FALSE when pad is a NULL pointer)
  652.  
  653.    BUGS
  654.  
  655.         -
  656.  
  657.    SINCE
  658.  
  659.         ... version 2 of the superviewsupport.library.
  660.  
  661.    SEE ALSO
  662.  
  663.         SVSUP_FindControlPad, SVSUP_SaveControlPad, SVSUP_LoadControlPad
  664.  
  665. -----------------------------------------------------------------------------
  666.  
  667.    NAME
  668.         SVSUP_FindControlPad
  669.  
  670.    SYNOPSIS
  671.  
  672.         ULONG SVSUP_FindControlPad(struct SV_ControlPad *pad,
  673.         D0    -$7e                 A1
  674.  
  675.                                    UBYTE *name,
  676.                                    A2
  677.  
  678.                                    UBYTE **content)
  679.                                    A3
  680.  
  681.    FUNCTION
  682.  
  683.         A ControlPad-List consists of Tooltype-like entries in the form :
  684.         <Name>=<Content> or <Keyword>.
  685.  
  686.         This function scans through such a list and searches for the
  687.         Content of an Entry with a specific name.
  688.         For Keywords the result is TRUE, but the Content pointer will
  689.         be NULL nevertheless.
  690.  
  691.         Searching IS case-sensitive !
  692.         Only READ-ACCESS to the content is allowed.
  693.  
  694.    INPUT(S)
  695.  
  696.         pad      - a pointer to a ControlPad-Structure (List-Head)
  697.         name     - the name of the entry to search for
  698.         content  - a pointer to a string pointer
  699.                    (the string pointer will be initialized with a pointer
  700.                     to the Content or NULL)
  701.  
  702.    RESULT
  703.  
  704.         Boolean value.
  705.  
  706.    BUGS
  707.  
  708.         -
  709.  
  710.    SINCE
  711.  
  712.         ... version 2 of the superviewsupport.library.
  713.  
  714.    SEE ALSO
  715.  
  716.         SVSUP_LoadControlPad, SVSUP_SaveControlPad, SVSUP_FreeControlPad
  717.  
  718. -----------------------------------------------------------------------------
  719.    Functions available since Version 3 :
  720. -----------------------------------------------------------------------------
  721.  
  722.    NAME
  723.         SVSUP_BitPlaneToOnePlane8
  724.  
  725.    SYNOPSIS
  726.  
  727.         ULONG SVSUP_BitPlaneToOnePlane8(struct SV_GfxBuffer *gfxb,
  728.         D0    -$84                      A1
  729.  
  730.                                         struct SV_GfxBuffer **destgfxb)
  731.                                         A2
  732.  
  733.    FUNCTION
  734.  
  735.         This function takes a GfxBuffer of type BITPLANE and creates
  736.         a GfxBuffer of type ONEPLANE out of it. This works with upto
  737.         8 Bit ColorDepth (256 Colors).
  738.  
  739.         The new GfxBuffer has to be given free by the user.
  740.  
  741.    INPUT(S)
  742.  
  743.         gfx      - a pointer to the Source GfxBuffer (BITPLANE)
  744.         destgfx  - a pointer to a pointer for the Destination
  745.                    GfxBuffer (ONEPLANE)
  746.  
  747.    RESULT
  748.  
  749.         NULL or a SVERR-Errorcode.
  750.  
  751.    BUGS
  752.  
  753.         -
  754.  
  755.    SINCE
  756.  
  757.         ... version 3 of the superviewsupport.library.
  758.  
  759.    SEE ALSO
  760.  
  761.         SVSUP_OnePlaneToBitPlane8
  762.  
  763. -----------------------------------------------------------------------------
  764.    NAME
  765.         SVSUP_OnePlaneToBitPlane8
  766.  
  767.    SYNOPSIS
  768.  
  769.         ULONG SVSUP_OnePlaneToBitPlane8(struct SV_GfxBuffer *gfxb,
  770.         D0    -$8a                      A1
  771.  
  772.                                         struct SV_GfxBuffer **destgfxb)
  773.                                         A2
  774.  
  775.    FUNCTION
  776.  
  777.         This function takes a GfxBuffer of type ONEPLANE and creates
  778.         a GfxBuffer of type BITPLANE out of it. This works with upto
  779.         8 Bit ColorDepth (256 Colors).
  780.  
  781.         The new GfxBuffer has to be given free by the user.
  782.  
  783.    INPUT(S)
  784.  
  785.         gfx      - a pointer to the Source GfxBuffer (ONEPLANE)
  786.         destgfx  - a pointer to a pointer for the Destination
  787.                    GfxBuffer (BITPLANE)
  788.  
  789.    RESULT
  790.  
  791.         NULL or a SVERR-Errorcode.
  792.  
  793.    BUGS
  794.  
  795.         -
  796.  
  797.    SINCE
  798.  
  799.         ... version 3 of the superviewsupport.library.
  800.  
  801.    SEE ALSO
  802.  
  803.         SVSUP_BitPlaneToOnePlane8
  804.  
  805. -----------------------------------------------------------------------------
  806.  
  807.    NAME
  808.         SVSUP_ScreenToOnePlane8
  809.  
  810.    SYNOPSIS
  811.  
  812.         ULONG SVSUP_ScreenToOnePlane8(struct Screen *sc,
  813.         D0    -$90                    A1
  814.  
  815.                                       struct SV_GfxBuffer **destgfxb)
  816.                                       A2
  817.  
  818.    FUNCTION
  819.  
  820.         This function takes an Intuition Screen and creates
  821.         a GfxBuffer of type ONEPLANE out of it. This works with upto
  822.         8 Bit ColorDepth (256 Colors).
  823.  
  824.         The new GfxBuffer has to be given free by the user.
  825.  
  826.    INPUT(S)
  827.  
  828.         gfx      - a pointer to an Intuition Screen
  829.         destgfx  - a pointer to a pointer for the Destination
  830.                    GfxBuffer (ONEPLANE)
  831.  
  832.    RESULT
  833.  
  834.         NULL or a SVERR-Errorcode.
  835.  
  836.    BUGS
  837.  
  838.         -
  839.  
  840.    SINCE
  841.  
  842.         ... version 3 of the superviewsupport.library.
  843.  
  844.    SEE ALSO
  845.  
  846.         SVSUP_ScreenToBitPlane8
  847.  
  848. -----------------------------------------------------------------------------
  849.    NAME
  850.         SVSUP_ScreenToBitPlane8
  851.  
  852.    SYNOPSIS
  853.  
  854.         ULONG SVSUP_ScreenToBitPlane8(struct Screen *sc,
  855.         D0    -$96                    A1
  856.  
  857.                                       struct SV_GfxBuffer **destgfxb)
  858.                                       A2
  859.  
  860.    FUNCTION
  861.  
  862.         This function takes an Intuition Screen and creates
  863.         a GfxBuffer of type BITPLANE out of it. This works with upto
  864.         8 Bit ColorDepth (256 Colors).
  865.  
  866.         The new GfxBuffer has to be given free by the user.
  867.  
  868.    INPUT(S)
  869.  
  870.         gfx      - a pointer to an Intuition Screen
  871.         destgfx  - a pointer to a pointer for the Destination
  872.                    GfxBuffer (BITPLANE)
  873.  
  874.    RESULT
  875.  
  876.         NULL or a SVERR-Errorcode.
  877.  
  878.    BUGS
  879.  
  880.         -
  881.  
  882.    SINCE
  883.  
  884.         ... version 3 of the superviewsupport.library.
  885.  
  886.    SEE ALSO
  887.  
  888.         SVSUP_ScreenToOnePlane8
  889.  
  890. -----------------------------------------------------------------------------
  891.    Functions available since Version 4 :
  892. -----------------------------------------------------------------------------
  893.  
  894.    NAME
  895.         SVSUP_DisplayGfxBuffer
  896.  
  897.    SYNOPSIS
  898.  
  899.         ULONG SVSUP_DisplayGfxBuffer(struct SVSUP_DisplayHandle *disphandle)
  900.         D0    -$9c                   A1
  901.  
  902.    FUNCTION
  903.  
  904.         This function allows displaying of GfxBuffers, e.g. for
  905.         test-purposes.
  906.  
  907.         This will may you, if you simply want to check the results
  908.         of self-created GfxBuffers or compare the results of
  909.         a GfxBuffer-conversion via e.g. SVSUP_OnePlaneToBitPlane8.
  910.  
  911.         The following code is quite senseless, because it is much easier
  912.         to use SVL_DisplayGfxBuffer() instead, but it demonstrates
  913.         quite good, how this function may be used (and _this_ example
  914.         definitely works ...) :
  915.  
  916.         ULONG GfxBufferShow(char *filename)
  917.          {
  918.           ULONG                       retval        = SVERR_NO_ERROR;
  919.           APTR                        handle        = N;
  920.           struct SVSUP_DisplayHandle *displayhandle = N;
  921.  
  922.           displayhandle = AllocVec(sizeof(struct SVSUP_DisplayHandle), MEMF_CLEAR|MEMF_PUBLIC);
  923.           if(displayhandle)
  924.            {
  925.             SVL_GetGlobalDriver(&displayhandle->SVDriverNode, N);
  926.  
  927.             handle = SVL_AllocHandle(N);
  928.             if(handle)
  929.              {
  930.               if(!(retval = SVL_InitHandleAsDOS(handle, N)))
  931.                {
  932.                 displayhandle->WinIDCMP = IDCMP_MOUSEBUTTONS;
  933.                 displayhandle->ScrType  = CUSTOMSCREEN;
  934.  
  935.                             retval = SVL_ReadToGfxBuffer(handle, filename);
  936.                 if(!retval) retval = SVL_GetGfxBuffer(   handle, &displayhandle->SVGfxBuffer, N);
  937.  
  938.                 if(!retval && displayhandle->SVGfxBuffer)
  939.                  {
  940.                   retval = SVSUP_DisplayGfxBuffer(displayhandle);
  941.                   if(!retval)
  942.                    {
  943.                     if(displayhandle->Window)
  944.                      {
  945.                       WaitPort(displayhandle->Window->UserPort);
  946.                      }
  947.                    }
  948.  
  949.                   SVSUP_UnDisplayGfxBuffer(displayhandle);
  950.                  }
  951.                }
  952.  
  953.               SVL_FreeHandle(handle);
  954.  
  955.              }else retval = SVERR_NO_HANDLE;
  956.  
  957.             FreeVec(displayhandle);
  958.  
  959.            }else retval = SVERR_NO_MEMORY;
  960.  
  961.           return(retval);
  962.          }
  963.  
  964.  
  965.         The Handle has to be allocated and initialized before passing it
  966.         to this function. After usage - and after calling SVSUP_UnDisplay-
  967.         GfxBuffer() - it has still to be delocated.
  968.  
  969.         You do not need (or must) initialize all fields of the Handle
  970.         structure, but set them to NULL, if you do not (or must not).
  971.         It is suggested, that you'll use AllocMem/AllocVec() with the
  972.         MEMF_CLEAR flag.
  973.  
  974.         Initialize at least the following fields :
  975.  
  976.           - Version              (currently 4)
  977.           - SVGfxBuffer          (the GfxBuffer)
  978.           - SVDriverNode         (as returned by SVL_GetGlobalDriver)
  979.  
  980.         Optionally initialize the following fields :
  981.  
  982.           - WinIDCMP
  983.           - WinFlags
  984.           - ScrType
  985.  
  986.         After calling SVSUP_DisplayGfxBuffer(), but before
  987.         SVSUP_UnDisplayGfxBuffer() you may use the following fields
  988.         for read-only purposes ::
  989.  
  990.           - Window;
  991.           - Screen;
  992.  
  993.  
  994.         All values are used and have to be interpreted just like the
  995.         corresponding parameters of the similar SVL_/SVO_ or SVD_
  996.         function calls :
  997.         If you do not supply values for ScreenType, WindowIDCMP and
  998.         WindowFlags, default-values will be used instead.
  999.  
  1000.    INPUT(S)
  1001.  
  1002.         displayhandle - a handle, as defined in "superviewsupport.h".
  1003.                         Has to be allocated and initalized by the User !!
  1004.  
  1005.    RESULT
  1006.  
  1007.         NULL or a SVERR-Errorcode.
  1008.  
  1009.    BUGS
  1010.  
  1011.         -
  1012.  
  1013.    SINCE
  1014.  
  1015.         ... version 4 of the superviewsupport.library.
  1016.  
  1017.    SEE ALSO
  1018.  
  1019.         SVSUP_UnDisplayGfxBuffer
  1020.  
  1021. -----------------------------------------------------------------------------
  1022.  
  1023.    NAME
  1024.         SVSUP_UnDisplayGfxBuffer
  1025.  
  1026.    SYNOPSIS
  1027.  
  1028.         ULONG SVSUP_UnDisplayGfxBuffer(struct SVSUP_DisplayHandle *disphandle)
  1029.         D0    -$a2                     A1
  1030.  
  1031.    FUNCTION
  1032.  
  1033.         This function closes a display, which has been opened via
  1034.         SVSUP_DisplayGfxBuffer() before.
  1035.  
  1036.         All temporary buffers etc. will be delocated, then.
  1037.         The supplied GfxBuffer and the Handle itself will be left intact.
  1038.  
  1039.         This call requires a valid displayhandle (which has been passed
  1040.         to SVSUP_DisplayGfxBuffer before).
  1041.  
  1042.         See SourceCode-example under SVSUP_DisplayGfxBuffer().
  1043.  
  1044.    INPUT(S)
  1045.  
  1046.         displayhandle - a handle, as defined in "superviewsupport.h".
  1047.                         Has still to be delocated by the User !!
  1048.  
  1049.    RESULT
  1050.  
  1051.         -
  1052.  
  1053.    BUGS
  1054.  
  1055.         -
  1056.  
  1057.    SINCE
  1058.  
  1059.         ... version 4 of the superviewsupport.library.
  1060.  
  1061.    SEE ALSO
  1062.  
  1063.         SVSUP_DisplayGfxBuffer
  1064.  
  1065. -----------------------------------------------------------------------------
  1066.  
  1067.    NAME
  1068.         SVSUP_FreeGfxBuffer
  1069.  
  1070.    SYNOPSIS
  1071.  
  1072.         ULONG SVSUP_FreeGfxBuffer(struct SV_GfxBuffer *gfxbuffer)
  1073.         D0    -$a8                A1
  1074.  
  1075.    FUNCTION
  1076.  
  1077.         Use this function to free GfxBuffers, which are not related to
  1078.         any SVObject-Handles.
  1079.  
  1080.         E.g. any of the SVSUP_ScreenToXXXPlane() and SVSUP_XXXPlaneToXXXPlane()
  1081.         functions produce GfxBuffer, which have to be given free either
  1082.         via separate FreeVec() calls for the ImageData-Buffer and for
  1083.         the GfxBuffer itself or just by calling this function and then
  1084.         forgetting about it.
  1085.  
  1086.         Do not try to free buffers, which will already be freed via the
  1087.         next SVL_FreeHandle call.
  1088.         These are Buffers, which are returned by SVL_GetGfxBuffer().
  1089.  
  1090.    INPUT(S)
  1091.  
  1092.         gfxbuffer - a valid pointer to a "stand-alone" GfxBuffer
  1093.  
  1094.    RESULT
  1095.  
  1096.         -
  1097.  
  1098.    BUGS
  1099.  
  1100.         -
  1101.  
  1102.    SINCE
  1103.  
  1104.         ... version 4 of the superviewsupport.library.
  1105.  
  1106.    SEE ALSO
  1107.  
  1108.         SVSUP_ScreenToXXXPlane(), SVSUP_XXXPlaneToXXXPlane()
  1109.  
  1110.         (XXX = (Bit | One)
  1111.  
  1112. -----------------------------------------------------------------------------
  1113.